/*
 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.nio.channels;

import java.util.concurrent.atomic.AtomicReferenceFieldUpdater;
import java.io.IOException;


/**
 * 表示SelectableChannel与选择器注册的令牌。
 *
 * <p> 每次向选择器注册通道时都会创建一个选择键。
 * 键在通过调用其cancel方法、关闭其通道或关闭其选择器来取消之前,保持有效。
 * 取消一个键并不会立即将其从选择器中删除；
 * 而是将其添加到选择器的“已取消”键集中，以便在下一次选择操作中删除。
 * 密钥的有效性可以通过调用它的isValid方法来测试。
 *
 * <a name="opsets"></a>
 *
 * <p> 选择键包含两个表示int值的操作集。
 * 操作集的每一位表示键的通道支持的可选择操作的类别。
 *
 * <ul>
 *
 *   <li><p> 兴趣集确定，下次调用选择器的选择方法之一时，将测试哪些操作类别是否就绪。
 *   在创建键时，使用给定的值初始化兴趣集；
 *   稍后可以通过interestOps（int）方法更改它。</p></li>
 *
 *   <li><p> 就绪集合标识，键的通道已被键的选择器，检测到准备就绪的操作类别。
 *   选择器就绪集合在创建密钥时被初始化为零；
 *   它可以在选择操作期间由选择器更新，但不能直接更新。</p></li>
 *
 * </ul>
 *
 * <p> 这是一个提示，但不能保证某个类别中的操作可以由线程执行而不会导致线程阻塞。
 * 在选择操作完成后，就绪集最有可能是精确的。
 * 外部事件和在相应通道上调用的I/O操作可能会使其不准确。
 * 
 * 
 *
 * <p> 此类定义了所有已知的操作集位，
 * 但特定通道支持哪些位取决于每个频道SelectableChannel的子类定义一个validOps（）方法，
 * 该方法返回一个集合，该集合只标识通道支持的那些操作。
 * 试图设置或测试，键的通道不支持的操作位，将导致适当的运行时异常。
 *
 * <p> 通常需要将某些特定于应用程序的数据与选择密钥相关联，
 * 例如，表示更高级别协议状态并处理就绪通知的对象，以便实现该协议。
 * 因此，选择键支持将单个任意对象附加到键。
 * 一个对象可以通过attach方法进行连接，然后通过attachment方法进行检索。
 *
 * <p> 多个并发线程可以安全地使用选择键。
 * 读写兴趣集的操作通常与选择器的某些操作同步。
 * 这种同步的具体执行方式取决于实现：
 * 在朴素的实现中，如果选择操作已经在进行中，则读取或写入兴趣集可能会不确定地阻塞；
 * 在高性能实现中，如果是，则读取或写入兴趣集可能会短暂阻塞。
 * 在任何情况下，选择操作将始终使用操作开始时的当前兴趣设置值。</p>
 *
 *
 * @author Mark Reinhold
 * @author JSR-51 Expert Group
 * @since 1.4
 *
 * @see SelectableChannel
 * @see Selector
 */

public abstract class SelectionKey {

    /**
     * Constructs an instance of this class.
     */
    protected SelectionKey() { }


    // -- Channel and selector operations --

    /**
     * 返回为其创建此密钥的通道。此方法将继续返回通道，即使在键被取消之后。
     *
     * @return  This key's channel
     */
    public abstract SelectableChannel channel();

    /**
     * 返回为其创建此键的选择器。即使在取消键之后，此方法仍将继续返回选择器。
     *
     * @return  This key's selector
     */
    public abstract Selector selector();

    /**
     * 指示此密钥是否有效。
     *
     * <p> 一个键在创建时是有效的，直到它被取消，它的频道被关闭，或者它的选择器被关闭。</p>
     *
     * @return  <tt>true</tt> if, and only if, this key is valid
     */
    public abstract boolean isValid();

    /**
     * 请求取消此密钥的通道与其选择器的注册。
     * 返回后，密钥将无效，并将添加到其选择器的取消密钥集中。
     * 在下一次选择操作中，将从选择器的所有按键集中删除该键。
     *
     * <p> 如果此键已被取消，则调用此方法无效。
     * 一旦取消，密钥将永远无效。</p>
     *
     * <p>可以随时调用此方法。
     * 它与选择器的已取消密钥集同步，因此，
     * 如果与涉及同一选择器的取消或选择操作同时调用，则可能会短暂阻塞。</p>
     */
    public abstract void cancel();


    // -- Operation-set accessors --

    /**
     * 检索此键的兴趣集。
     *
     * <p> 保证返回的集合只包含对该键的通道有效的操作位。
     *
     * <p> 可以随时调用此方法。
     * 它是否阻塞以及阻塞的时间长短取决于实现。</p>
     *
     * @return  This key's interest set
     *
     * @throws  CancelledKeyException
     *          If this key has been cancelled
     */
    public abstract int interestOps();

    /**
     * 将此键的兴趣集设置为给定值。
     *
     * <p>可以随时调用此方法。它是否阻塞以及阻塞的时间长短取决于实现。 </p>
     *
     * @param  ops  The new interest set
     *
     * @return  This selection key
     *
     * @throws  IllegalArgumentException
     *          If a bit in the set does not correspond to an operation that
     *          is supported by this key's channel, that is, if
     *          {@code (ops & ~channel().validOps()) != 0}
     *
     * @throws  CancelledKeyException
     *          If this key has been cancelled
     */
    public abstract SelectionKey interestOps(int ops);

    /**
     * 检索此键的就绪操作集。
     *
     * <p> 保证返回的集合只包含对该键的通道有效的操作位。</p>
     *
     * @return  This key's ready-operation set
     *
     * @throws  CancelledKeyException
     *          If this key has been cancelled
     */
    public abstract int readyOps();


    // -- Operation bits and bit-testing convenience methods --

    /**
     * 用于读取操作的操作设置位。
     *
     * <p> 假设一个选择键的兴趣集在选择操作开始时包含OP_READ。
     * 如果Selector检测到相应的通道已准备好读取、
     * 已到达流的末尾、已被远程关闭以进行进一步读取或有错误挂起，
     * 则它会将OP_READ添加到密钥的ready-operation集中，并将该密钥添加到其选定的密钥集中。</p>
     */
    
    public static final int OP_READ = 1 << 0;

    /**
     * 写入操作的操作设置位。
     *
     * <p> 假设选择键的兴趣集在选择操作开始时包含“操作写入”。
     *  如果选择器检测到相应的通道已准备好写入，已被远程关闭以进行进一步写入，或有一个待决错误，
     *  则它将向密钥的就绪集添加OP_WRITE，并将该密钥添加到其选定的密钥集中。</p>
     */
    public static final int OP_WRITE = 1 << 2;

    /**
     * 套接字连接操作的操作设置位。
     *
     * <p> 假设选择键的兴趣集在选择操作开始时包含OP_CONNECT。
     * 如果Selector检测到相应的套接字通道已准备好完成其连接序列，或者有一个挂起的错误，
     * 则它会将OP_CONNECT添加到密钥的就绪集，并将密钥添加到其选定的密钥集。</p>
     */
    public static final int OP_CONNECT = 1 << 3;

    /**
     * 套接字接受操作的操作设置位。
     *
     * <p> 假设选择键的兴趣集在选择操作开始时包含OP_ACCEPT。
     * 如果Selector检测到相应的服务器套接字通道已准备好接受另一个连接，或者有一个挂起的错误，
     * 那么它将把OP_ACCEPT添加到密钥的ready set，并将该密钥添加到它所选的密钥集中。</p>
     */
    public static final int OP_ACCEPT = 1 << 4;

    /**
     * 测试此键的频道是否准备好读取。
     *
     * <p> 以k.isReadable（）形式调用此方法的行为与表达式的方式完全相同
     *
     * <blockquote><pre>{@code
     * k.readyOps() & OP_READ != 0
     * }</pre></blockquote>
     *
     * <p> 如果此键的通道不支持读取操作，则这个方法始终返回false。
     *
     * @return  <tt>true</tt> if, and only if,
                {@code readyOps() & OP_READ} is nonzero
     *
     * @throws  CancelledKeyException
     *          If this key has been cancelled
     */
    public final boolean isReadable() {
        return (readyOps() & OP_READ) != 0;
    }

    /**
     * 测试此键的频道是否准备好读取。
     *
     * <p> 以k.isWritable（）形式调用此方法的行为与表达式的方式完全相同
     *
     * <blockquote><pre>{@code
     * k.readyOps() & OP_WRITE != 0
     * }</pre></blockquote>
     *
     * <p> 如果此键的通道不支持写入操作，则这个方法始终返回false。 </p>
     *
     * @return  <tt>true</tt> if, and only if,
     *          {@code readyOps() & OP_WRITE} is nonzero
     *
     * @throws  CancelledKeyException
     *          If this key has been cancelled
     */
    public final boolean isWritable() {
        return (readyOps() & OP_WRITE) != 0;
    }

    /**
     * 测试此键的频道是否准备好读取。
     *
     * <p> 以k.isConnectable（）形式调用此方法的行为与表达式的方式完全相同
     *
     * <blockquote><pre>{@code
     * k.readyOps() & OP_CONNECT != 0
     * }</pre></blockquote>
     *
     * <p>如果此键的通道不支持套接字连接操作，则这个方法始终返回false。</p>
     *
     * @return  <tt>true</tt> if, and only if,
     *          {@code readyOps() & OP_CONNECT} is nonzero
     *
     * @throws  CancelledKeyException
     *          If this key has been cancelled
     */
    public final boolean isConnectable() {
        return (readyOps() & OP_CONNECT) != 0;
    }

    /**
     * 测试此键的频道是否准备好读取。
     *
     * <p> 以k.isAcceptable（）形式调用此方法的行为与表达式的方式完全相同
     *
     * <blockquote><pre>{@code
     * k.readyOps() & OP_ACCEPT != 0
     * }</pre></blockquote>
     *
     * <p> 如果此键的通道不支持套接字接受操作，则这个方法始终返回false。  </p>
     *
     * @return  <tt>true</tt> if, and only if,
     *          {@code readyOps() & OP_ACCEPT} is nonzero
     *
     * @throws  CancelledKeyException
     *          If this key has been cancelled
     */
    public final boolean isAcceptable() {
        return (readyOps() & OP_ACCEPT) != 0;
    }


    // -- Attachments --

    private volatile Object attachment = null;

    private static final AtomicReferenceFieldUpdater<SelectionKey,Object>
        attachmentUpdater = AtomicReferenceFieldUpdater.newUpdater(
            SelectionKey.class, Object.class, "attachment"
        );

    /**
     * 将给定对象附加到此键。
     *
     * <p> 附加对象可以稍后通过attachment方法检索。
     * 一次只能附加一个对象；
     * 调用此方法将导致放弃以前的任何附件。
     * 可以通过附加null来丢弃当前的附件。</p>
     *
     * @param  ob
     *         The object to be attached; may be <tt>null</tt>
     *
     * @return  The previously-attached object, if any,
     *          otherwise <tt>null</tt>
     */
    public final Object attach(Object ob) {
        return attachmentUpdater.getAndSet(this, ob);
    }

    /**
     * 返回当前的附件
     *
     * @return  The object currently attached to this key,
     *          or <tt>null</tt> if there is no attachment
     */
    public final Object attachment() {
        return attachment;
    }

}
